WIDGET_DISPLAYCONTEXTMENU

The WIDGET_DISPLAYCONTEXTMENU procedure displays a context-sensitive menu (also known as a pop-up or shortcut menu). Context-sensitive menus appear when the user clicks the right mouse button over a widget for which a context menu is defined. Because the widget programmer must explicitly detect the right-mouse button click and call WIDGET_DISPLAYCONTEXTMENU to display the context menu, a widget can have any number of associated context menus, which can be displayed under different circumstances.

Context menus are created by placing one or more button widgets on a base widget constructed with the CONTEXT_MENU keyword set. The context menu’s base widget must have as its parent a base, draw, list, property sheet, table, tree or text widget; in the case of all but draw widgets, the parent widget must be configured to generate context menu events via the CONTEXT_EVENTS keyword. Draw widgets that support context menus must have the BUTTON_EVENTS keyword set.

The widget application’s event handler routine must detect the presence of a context menu event (base, list, and text widgets) or the right mouse-button event (draw and property sheet widgets) and call WIDGET_DISPLAYCONTEXTMENU to display the context menu. Events generated when the user clicks on the context menu’s buttons are handled in the normal way. If the user clicks outside the context menu, it is dismissed and no event is generated.

Examples

For examples using WIDGET_DISPLAYCONTEXTMENU, see Context-Sensitive Menus.

Syntax

WIDGET_DISPLAYCONTEXTMENU, Parent, X, Y, ContextBase_ID

Arguments

Parent

The widget ID of the parent widget of the context menu widget.

Note: The parent widget must be either a base, list, or text widget with the CONTEXT_EVENTS keyword set or a draw widget with the BUTTON_EVENTS keyword set. In most cases the parent widget can be identified via the ID field of the WIDGET_CONTEXT or WIDGET_DRAW event structure.

X

The x location, relative to the parent widget, at which the menu should be displayed. (In most cases this will be the x location of the user’s right mouse-button click, as reported in the X field of the WIDGET_CONTEXT or WIDGET_DRAW event structure.)

Y

The y location, relative to the parent widget, at which the menu should be displayed. (In most cases this will be the y location of the user’s right mouse-button click, as reported in the Y field of the WIDGET_CONTEXT or WIDGET_DRAW event structure.)

ContextBase_ID

The widget ID of the context menu base widget that contains the context menu to be displayed. Use the CONTEXT_MENU keyword to WIDGET_BASE to create a context menu base.

Note: The context menu base must be a child of the widget specified by the Parent argument.

Keywords

None

Version History

5.5	Introduced